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PREFACE 



This publication is intended fcr the prob- 
lem programmer assigned to write a message 
processing program to support a QTAM- 
controlled telecommunications system 
operating under the IBM System/360 Oper- 
ating System. Included is a general dis- 
cussion of message processing programs, 
followed by a detailed description of the 
services QTAM provides in support of a mes- 
sage processing program. The QTAM services 
are provided through standard macro- 
language statements such as GET, PUT, OPEN, 
and CLOSE. 



The first four sections of a companion 
publication, IBM System/360 Operating Sys- 
tem; CTAM Message Control Program , Form 
C30-200 5, contain general information of 
interest to the programmer writing a mes- 
sage processing program, i.e., telecommu- 
nications applications, concepts and ter- 
minology, and message formats. 

The prerequisite fcr a thorough under- 
standing of this publication is a basic 
knowledge of System/3 60 machine concepts 
and of the System/360 Operating System. 
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INTRODUCTION 



In the IBM System/360 Operating System, an 
access method is a procedure for transfer- 
ring data between main storage and an 
input/output device. A variety of access 
methods is available to the user of the 
operating system. One of these, the Queued 
Telecommunications Access Method (QTAM) , 
controls data transfer between main storage 
and remote terminals. 

QTAM is a generalized input/output con- 
trol system that extends the techniques of 
data management to the telecommunications 
environment. Data sets accessed by the 
problem programmer are queues of messages 
incoming from, or outgoing to, remote ter- 
minals via communication lines. Even 
though the time and order of the arrival 
and departure of messages to and from the 
central processing unit (CPU) are unpre- 
dictable, the programmer handles them as if 
they were organized sequentially. 

Unlike other commonly used access 
methods, QTAM furnishes more than just the 
mechanics for input/output operations. In 
addition to the standard GET/PUT macro in- 
struction support for message processing 
programs, QTAM provides a high-level and 
flexible message control language. QTAM- 
supplied macro instructions can be used to 
construct a complete message control pro- 
gram that controls the flow of message 
traffic from one remote terminal to another 
(message switching application) , and 
between remote terminals and any message 
processing programs (message processing 
applications) . 

A QTAM message control program is com- 
pletely device- dependent, with all communi- 
cation lines and terminals identified to 
the system. Through data set definition 
and control information macro instructions, 
the user specifies his equipment configura- 
tion and the main storage areas (buffers) 
required for his applications. These 
macros generate the tables and lists of 



control information that define the 
environment of the system for the QTAM 
logic. The number and size of the buffers 
required are specified by the user, and are 
one of the primary resources in the tele- 
communications system. The buffers are 
allocated to a common buffer pool from 
which QTAM automatically and dynamically 
uses them in accordance with immediate 
requirements . 



The message processing program services 
of QTAM enable a programmer to process mes- 
sages from a telecommunications network 
with the same easy-to-use macro instruc- 
tions that he uses for his local input/ 
output devices. Because a QTAM message 
control program performs the input/output 
operations, a completely device-independent 
message processing program can be written. 
The programmer is shielded from the time 
and device-dependent aspects of the tele- 
communications environment. 

For a QTAM message control program to 
handle the flow of message data between a 
message processing program and the remote 
terminals in a system, there must be an 
interface between the message control pro- 
gram and the message processing program. 
QTAM (in the form of macro instructions) 
provides facilities that enable the pro- 
grammer to establish this interface from 
the message processing program. 

This publication describes in detail the 
services QTAM provides in support of a mes- 
sage processing program. The message con- 
trol program is discussed in general terms 
when necessary to give a complete picture 
of how a message processing program fits 
into a QTAM-controlled telecommunications 
system. For detailed information on the 
message control program, refer to the pub- 
lication IBM System/3 60 Operating System; 
QTAM Message Control Program , Form 
C30-2005. 
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GENERAL CONCEPTS OF A MESSAGE PROCESSING PROGRAM 



In telecommunications terminology, a mes- 
sage is the unit of work with which the 
programmer is concerned when he writes a 
processing program. A message is composed 
of two parts: the message header and the 
message text. The header portion contains 
control information about a particular mes- 
sage used by the message control program in 
performing its functions. This information 
can include a destination code (for 
example, a message processing program), the 
code name of the originating terminal 
(source code) , a message-type indicator, 
and other fields containing control-type 
data. The text portion of a message con- 
sists of the information of concern to the 
party receiving the message. This party 
can be a message processing program. 

A message processing program normally 
consists of an analysis routine and/or pro- 
cessing routines that take action on the 
text portion of a message. £ response mes- 
sage may or may not be generated. 

An analysis routine is user-written cod- 
ing that examines the content of a message 
to determine which course of action is to 
be taken. With this decision, the analysis 
routine establishes linkage to the process- 
ing routine required to perform the neces- 
sary action on the message. The complexity 
of the analysis routine varies directly 
with the total number of courses of action 
that can be required by the incoming mes- 
sages. The same method should be used for 
detecting all message types. Fcr example, 
a message-type character can always appear 
in a prespecified position in the message 
header or in the first position of the 
text. 

The processing required may be standard 
for all messages routed to a message pro- 
cessing program. In this case, an analysis 
routine is not required. 

All processing routines are also user- 
provided. There must be one processing 
routine for each specific course of action 
required by a message. A message process- 
ing routine is required when the user 
wishes to cause a shutdown of the QTAM mes- 
sage control program. At execution time, a 
processing routine resides either in main 
storage, as an integral part of the message 
processing program, or on a DASD library. 
If the latter method is selected, each pro- 
cessing routine is assembled or compiled 
independently of the rest of the message 
processing program. It is linkage edited 
onto a DASD library and brought into main 



storage dynamically as needed via a LINK 
macro instruction. Unlike a message con- 
trol program, the message processing pro- 
gram may contain control program services 
(CPS) macro instructions as well as QTAM 
macro instructions. 



Note : The user must insure that the 
operating system subroutine error trace 
scheme can function. This may be done by 
making a SAVE macro the first instruction 
in each message processing program. For 
detailed information, see IBM System/360 
Operating System: Supervisor and Data 
Management Services , Form C28-66H6. 

QTAM provides certain functions in sup- 
port of a message processing program and 
the telecommunications system. These func- 
tions include: 



1. Obtaining a message for processing, 

2. Placing a response message, if any, on 
a destination queue or another process 
queue. 



These two functions (unlike the functions 
performed by the processing routine and the 
analysis routine) are peculiar to QTAM, 
which provides macro instructions to aid in 
performing them. 

The GET macro instruction obtains a mes- 
sage from the main storage process queue 
and places it in a user-specified work 
area, where it is then analyzed and pro- 
cessed. The PUT macrc instruction causes a 
response message to be placed on a destina- 
tion queue. These macro instructions are 
described in detail under the Obtaining 
Messages and Placing Response Messages 
section. 

A QTAM message control program performs 
the actual input/output operations required 
by a message processing program. The mes- 
sage control program must be executed in 
the highest priority partition or region. 
As many message processing programs as 
there are partitions cr regions remaining 
can operate concurrently with the message 
control program. Each message processing 
program must operate in a partition or 
region separate from ether message process- 
ing programs and from the message control 
program in order for QTAM to provide asyn- 
chronous operation for all programming com- 
ponents of the system. 
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After being assembled, linkage edited, 
and placed on a library, a message process- 
ing program can be executed by placing the 
appropriate job control cards in the input 
job stream, following the job ccntrol cards 
for the message control program, or for a 
different message processing program. 



Figure 1 shows a sample structure for a 
message processing program. The DCB macro 
instructions define the data control block 
for the main storage process and destina- 
tion queues. The user must define all 
queues referred to by his program. The 
OPEN macro instruction prepares these data 
control blocks for use in processing. The 
statement "other initialization instruc- 
tions" represents any instructions the user 
wishes to include to clear storage areas, 
etc. GET obtains a message. The "analy- 
sis" instructions determine which process- 
ing routine is needed to process the mes- 
sage. The appropriate LINK iracro instruc- 
tion brings the specified processing rou- 
tine into main storage and executes the 
routine. Response messages generated by 
the processing routine are placed on the 
appropriate destination queue by the PUT 
macro instruction. 



The user then performs a test to deter- 
mine whether processing should terminate. 
If processing should continue, the program 
branches to GET to obtain the next message. 
If processing should terminate, the program 
performs any necessary termination 
functions. 



The program structure shown in Figure 1 
assumes that no EODAD keyword operand was 
specified in the DCB macro instruction for 
the main storage process queue. If no mes- 
sage has been placed in the main storage 
process queue by the message control pro- 
gram, the message processing program enters 
a wait state, and is reentered cnly when a 
message arrives for this main storage pro- 
cess queue. 



DCB 
DCB 

(other definition macro instructions) 



OPEN 



(other initialization macro instructions) 



■►GET 



(macro instructions for analyzing message) 



LINK A 



LINK B 



LINK C 



PUT 




(perform termination functions) 



CLOSE MC 

CLOSE 
RETURN 



Figure 1. Sample Structure for a Message 
Processing Program 
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MESSAGE FLOW WITHIN THE SYSTEM 



This section describes the flow of a mes- 
sage between a remote terminal and a mes- 
sage processing program operating under 
QTAM. The manner in which a QTAM message 
control program acts as an intermediary 
between the terminal and the message pro- 
cessing program is discussed in some 
detail. Figure 2 illustrates this flow. 

The input message is prepared at the 
remote terminal location. Messages are of 
variable length and consist of two parts: 
header and text. The terminal sends the 
message to the computer via a communication 
line. Step 1 of Figure 2 shows the message 
passing through an IBM 2701, 2702, or 270 3 
control unit and the multiplexer channel,, 
and filling available buffers from the QTAM 
buffer pool defined in the message control 
program. 

The user defines the size of his buffers 
in the message control program. QTAM 
inserts control information (known as a 
prefix) in the first portion of each buf- 
fer. The first 32 bytes of a buffer, used 
to contain a message header, are set aside 
for a header prefix generated by QTAM. 
This buffer may contain text data in addi- 
tion to the header. However, the entire 
header must be contained in this buffer. 
The characters transmitted by the remote 
terminal begin to fill the buffer in the 
thirty-third byte. The first 22 bytes of a 
buffer used to contain text data only, are 
set aside for a text prefix generated by 
QTAM. Message data begins to fill the buf- 
fer in the twenty-third byte. 

The user transmits single-segment or 
multisegment messages. A message segment 
is message data that occupies one buffer* 
In single-segment messages, the entire mes- 
sage is contained within one buffer. In 
multisegment messages, more than one buffer 
is needed for a message. 

In all but the last buffer fcr a multi- 
segment message, the segment containing a 
header is shorter than a segment containing 
text only, because the header prefix 
generated by QTAM is ten bytes longer than 
the text prefix. In each buffer used to 
contain intermediate text, the segments are 
the same size. In the last buffer for a 
multisegment message, the message text por- 
tion of the segment can be any length equal 
to, or less than, the buffer length minus 
22. 

The buffers shown in Figure 2 are each 
80 bytes in length. The first input buffer 
thus accommodates a message segment of 48 
characters (26 constitute the header por- 
tion of the message and 22 constitute the 



text portion) . In the second input buffer, 
the message segment is 58 characters; all 
of which are text data. The third and last 
input buffer contains the remaining charac- 
ters in the message. Because the input 
message is 150 characters, the message seg- 
ment size for this buffer is 44. 

As soon as a buffer is filled with the 
first segment of a message, the receive 
group portion of the line procedure speci- 
fication (LPS) section of the message con- 
trol program performs user-selected func- 
tions such as code conversion, logging, 
updating of message counts, incorporation 
of time-received and date-received informa- 
tion, and input- sequence- number checking. 
The first three functions can also be per- 
formed for text segments. In the example 
shown in Figure 2, the user has specified 
that six characters of time-received infor- 
mation be incorporated into the message 
header (see Step 2). 

After performing these functions, the 
receive group of the LPS routes the prefix 
(minus the first eight bytes 1 ) and message 
segment to a DASD process queue on the DASD 
message queues data set. Each DASD process 
queue is associated with a message process- 
ing program. Messages requiring text pro- 
cessing should be routed to the DASD pro- 
cess queue associated with the message pro- 
cessing program that processes that type of 
message. The user controls this routing 
either via the message header (the destina- 
tion code is the name of the DASD process 
queue) or via LPS iracro instructions (which 
direct messages of a particular type to a 
particular queue) . Step 2 shows the LPS 
routing a message to a DASD process queue. 

For each DASD process queue maintained, 
QTAM maintains a corresponding queue in 
main storage. Each main storage (MS) pro- 
cess queue is maintained in buffers from 
the QTAM buffer pool in the message control 
program. The number of buffers allocated 
to a MS process queue is specified in a 
data control block defined in the message 
processing program that gets messages from 
that queue. After the data control block 
for the MS process queue has been opened by 
the message processing program, a QTAM rou- 
tine in the message control program auto- 
matically passes the message segment from 
the DASD process queue to a buffer in the 
MS process queue (see Step 3). In moving 
the prefix and segirent to the buffer, the 
eight bytes that were deleted when the pre- 
fix and segment were placed on the DASD 



±r The first eight bytes of a header or text 
prefix contain control information used 
only in main storage buffer handling. 
Therefore, these bytes are not placed on 
the direct access device. 
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process queue are restored, so that the 
prefix length is once again 32 (header pre- 
fix) or 22 (text prefix) . 

Each time the message processing program 
gains control and issues a GET (Step 4), 
QTAM passes message data frorr the MS pro- 
cess queue to a user-specified work area in 
the message processing program. Message 
data is provided in the work unit specified 
by the user in the data control block. The 
work unit may be a complete iressage, a mes- 
sage segment, or a record. Before moving 
the message data to the work area, QTAM 
strips the header and text prefixes from 
the message segments. QTAM places a four- 
byte prefix in the first four bytes of this 
work area. This prefix indicates the size 
and type of the work unit on which the pro- 
cessing program is to operate. After 
receiving the message data, the message 
processing program processes it as required 
by the application. 

A message processing program that 
generates a response message must define 
and open a data control block governing 
message transfer before it attempts to 
place the message on a DASD destination 
queue. This data control block contains 
information needed by QTAM to establish an 
MS destination queue. When a PUT macro in- 
struction is issued by a message processing 
program (Step 5) , QTAM moves the message 
data from the user-specified work area into 
the MS destination queue. The header and 
text prefixes are attached to the message 
segments in the buffer areas that make up 
the MS destination queue. 

As the message data fills the buffers,, 
QTAM inserts chaining addresses and other 



necessary control information into the pre- 
fix fields. The respcnse message generated 
by a message processing program can be any 
size. (The one used in Figure 2 is 12 
characters. ) 



After the header or text prefixes have 
been added in the MS destination queue, 
QTAM places the segment into the appropri- 
ate DASD destination queue on the DASD mes- 
sage queues data set (Step 6). 



QTAM retrieves message segments from the 
DASD destination queues on a first-in 
first-out basis within priority groups. 
The message segments are brought in from 
the direct access device and placed in 
available buffers (Step 7). The "send 
group" of the LPS section in the message 
control program then performs user-selected 
functions such as converting the code of 
the message to the transmission code of the 
terminal, incorporating time-sent and date- 
sent information in the header, message 
logging, and updating of message counts. 
These operations are performed in the buf- 
fers that receive the message segments from 
the direct access device. QTAM then strips 
the header and text prefixes from the mes- 
sage segments and transmits the message to 
the appropriate terminal (Step 8). 

The header and text prefixes described 
in this section are generated automatically 
and are used by QTAM routines. No program- 
ming considerations are required by the 
user for the manipulation of the buffers 
and their prefixes. They are described 
here to give a complete view of the message 
flow through the system. 
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Figure 2. QTAM Message Flow (Part 2 of 2) 
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MESSAGE PROCESSING PROGRAM SERVICES 



The routing of messages between a message 
processing program and remote terminals is 
handled by the QTAM message control pro- 
gram. Because a message processing program 
depends on the message control program to 
perform its input/output operations, an 
interface must be established between a 
message processing program and the message 
control program. QTAM provides the follow- 
ing services that allow this interface to 
be established from a message processing 
program: 



• Defines the message control progr 
interface (DCB macro instruction) 



gram 



• Initializes and activates the message 
control program interface (OPEN macro 
instruction) 

• Obtains messages and transfers response 
messages (GET and PUT macro 
instructions ) 

• Deactivates the message control program 
interface (CLOSEMC macro instruction) 

Unlike the functions performed by the 
analysis and processing routines of a mes- 
sage processing program, these functions 
are partially or wholly peculiar to QTAM 
and the telecommunications environment. 
Therefore, QTAM provides routines to accom- 
plish these functions. Linkage to these 
routines is established by QTAM macro 
instructions in a message processing pro- 
gram. The remainder of this section dis- 
cusses these macro instructions in detail. 



DEFINING THE MESSAGE CONTROL PROGRAM 
INTERFACE 



Message transfer from a main storage (MS) 
process queue to a message processing pro- 
gram is controlled by a data control block. 
If the message processing program generates 
a response message, message transfer from 
the message processing program to a main 
storage (MS) destination queue is governed 
by another data control block. The user 
must define, open, and close these data 
control blocks in the message processing 
program. 

A DCB macro instruction must be speci- 
fied for each MS process queue (queue pro- 
viding input to the message processing pro- 
gram) and for each MS destination queue 
(output queue) referred to by a message 



processing program. A DD statement must be 
provided for each DCB. The DD statement 
must contain only DUMMY in the operand 
field. This indicates that no I/O device 
is being assigned. The name of the DD 
statement must be identical with the name 
specified in the DDNAME keyword operand of 
its associated DCB macro instruction. 

Examples of DD statements for a message 
processing program are: 



r t t 1 

j Name | Operation] Operand | 

j. + + ., 

JMAINPQ JDD j DUMMY j 

y + + .J 

|RESPMT |DD ] DUMMY ] 

L X X J 



The data co 
expansion of t 
not associated 
Instead,, they 
information to 
the QTAM mess a 
uses this cont 
ring data to a 
ing program. 



ntrol blocks generated by the 
hese macro instructions are 

with data sets themselves, 
contain the necessary control 

establish the interface tp 
ge control program, which 
rol information in transfer- 
nd from the message process- 



The message control program performs the 
actual input/output operations needed to 
receive and send messages over communica- 
tion lines. The incoming messages that 
must be routed to a message processing pro- 
gram are first placed in the DASD process 
queue associated with the message process- 
ing program. After the data control block 
for the MS process queue has been opened, 
and the first GET macro instruction is 
issued in the message processing program, 
the message control program begins trans- 
ferring messages from the DASD process 
queue to the MS process queue. While the 
MS process queue remains open, the message 
control program automatically replenishes 
it with messages from the DASD process 
queue in anticipation of the next GET. 

Similarly, the MS destination queue must 
be defined (by a DCB macro instruction) and 
opened in the message processing program if 
a response message is to be sent. When a 
PUT macro instruction is issued, the PUT 
routine transfers the message to the MS 
destination queue and signals the message 
control program that a message is ready to 
be placed on a DASD destination queue. The 
message control program places the message 
on the appropriate DASD destination queue. 
Finally,, the message control program 
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retrieves the message from the DASD 
destination queue and transmits the message 
to the appropriate terminal. 

Messages generated by the message pro- 
cessing program can also be sent to another 
message processing program. This is accom- 
plished via a PUT macro instruction. The 
data flow is identical with that described 
previously for sending a message to a ter- 
minal,, except that message transfer from 
the MS destination queue is to a DASD pro- 
cess queue. 



Thus, the MS process and MS 
queues defined in the message 
program serve as the connector 
message control program and th 
processing program. When the 
control program is used as an 
between the message processing 
the remote terminals, the mess 
ing program is completely devi 
independent. 



destination 
processing 
s between the 
e message 
QTAM message 
intermediary 

program and 
age process- 
ce- 



Onlv one MS destination queue is 
required (and only if a response message is 
to be generated) „ regardless of the number 
of MS process queues. 



The DCB macro instruction causes the 
allocation of main storage space for a data 
control block at assembly time. Parameters 
based on the operands in the macro instruc- 
tion are included in the data control 
block. No executable code is generated 
through this macro. 



Figures 3 and 4 show the operands for 
DCB macro instructions for two data control 
blocks: the MS process queue DCB, and the 
MS destination queue, respectively. 



r t t — - — -- 1 

] Name ] Operation | Operand | 

] deb j DCB ] keyword operands j 

i x x . J 



Data Control Block (DCB) Macro Instruction 



In a message processing program, the DCb 
macro instruction defines two types of data 
control blocks. 

One data control block contains the in- 
formation needed to create the MS process 
queue from which messages can be obtained 
for processing. The other data control 
block contains the information needed to 
create the MS destination queue, and is 
required only if response messages are to 
be generated. 

Normally, only one MS process queue is 
defined in a message processing program. 
All message types to be processed by a par- 
ticular message processing program are 
obtained from the same MS process queue. 
An analysis routine determines the type of 
each message and establishes linkage to the 
appropriate processing routine. However, 
it is possible to have multiple MS process 
queues in the same message processing pro- 
gram; that is, one MS process queue for 
each type of message to be processed. In 
this case, the EODAD keyword operand should 
be used to regain control if no message 
appears in this MS process queue. Execu- 
tion of another GET from a different MS 
process queue can be effected, and so 
forth. 



deb 



The address of the DCR macro instruc- 
tion. The name must be specified. 



keyword operands 

The operands that can be included to 
facilitate the control of message 
transfer between the message process- 
ing program and a DASD process or DASD 
destination queue. The operands for 
the two types of DCB macro instruc- 
tions in the message orocessing pro- 
gram are described in Figures 3 and 4. 

When a parameter is provided by an 
alternate source, one or more symbols 
appear in the table. When there is no 
alternate source, no symbols are shown. 
The symbols have the following meanings: 



Symbol 

PP 



OE 



Meaning 

The value of the operand can 
be provided by the user's 
problem program any time 
before the data control 
block exit at open time., 

The value can be provided by 
the user's problem program 
any time up to and including 
the data control block exit 
provided at open time. 
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Keyword 
Operands 



Alternate 
Source 



Value Description 



DSORG=MQ 



■+- 



MQ 

Identifies the data control block as one 
governing message transfer to or from a 
telecommunications message processing queue. 
If this operand is omitted, the telecommuni- 
cations job, when executed, is terminated. 



MACRF=G 



Specifies that access to the MS process 
queue is to be gained with the GET macro in- 
struction. If this operand is omitted, the 
telecommunications job, when executed, is 

terminated. 



DDNAME=ddname 



PP 



ddname 

Is the name that appears in the DD statement 
associated with the data control block. 
This name is also the name used in the 
PROCESS macro instruction to identify the MS 
process queue. If this operand is omitted 
and the \alue is not provided through an 
alternate source, the telecommunications 
job, when executed, is terminated. 



BUFRQ=absexp" 
BUFRQ=0 



OE 



absexp 

Is the number of buffers to be requested in 
advance for the GET macro instruction, 
"absexp" must be less than 256. If this 
operand is omitted and the value not sup- 
plied by an alternate source,, BUFRQ=0 is 
assumed. 



SOWA=absexp 



OE 



absexp 

Is the size in bytes of the user-provided 
input work area; "absexp" must be less than 
32„7 68. This value must include the four- 
byte user prefix. If this operand is 
omitted and the value is not provided by an 
alternate source, the telecommunications 
job, when executed,, is terminated. 



Figure 3. Keyword Operands for the Main Storage Process Queue DCB 
Macro Instruction (Part 1 of 2) 
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T T 

Alternate 
Source 



| Keyword 
[Operands 



l-r- 



Value Description 



RECFM=G 
RECFM=S 



RECFM=R 



OE 



h 



G, S, or R 

Specifies the work unit as follows: 

G — message (defined by the end-of- 
transmission character). 

S — segment (defined by the buffer size) . 

R — record [defined by the carriage return 
(CR), line feed (LF), new line (NL), or 
end-of -block (EOB) character]. 

If this operand is omitted and the value is 
not supplied by an alternate source, RECFM=S 
is assumed. 



[E0DAD=relexp3 



OE 



h 



relexp 

Is the symbolic address of a user- provided 
routine to be entered if no messages are 
available when a GET macro instruction is 
issued. If this operand is oiritted and the 
value not supplied through an alternate 
source, a WAIT macro instruction is implied. 



[TRMAD=relexp] 



OE 



h- 



relexp 

Is the symbolic address of a user-provided 
area to contain the terminal name. When a 
GET macro instruction is issued, QTAM places 
the source terminal name at the specified 
address. The length of the area must be 
equal to or larger than the maximum size 
terminal name or process queue name used- 
If the Auto Poll facility or switched line 
groups are being used, the SOURCE macro in- 
struction is required in the LPS for these 
line groups. If this operand is omitted and 
the value is not provided through the 
alternate source, the telecommunications 
job, when executed, is terminated. 



t3YNAD=relexp] 



OE 



relexp 

Is the symbolic address of a user-provided 
routine to be entered if a work unit is 
longer than the work area provided for 
input. If this operand is omitted an3 the 
value is not provided through the alternate 
source, the remainder of the work unit is 
supplied when the next GST macro instruction 
is issued. Data remaining in the buffer, 
however, will be lost for a GET segment. 



Figure 3. Keyword Operands for the Main Storage Process Queue DCB 
Macro Instruction (Part 2 of 2) 
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T T 

Alternate 

Source 

-+ 



Keyword 
Operands 



Value Description 



DSORG=MC 



+- 



MQ 

Identifies the data control block as one 
governing message transfer to or from a 
telecommunications message processing queue. 
If this operand is omitted, the telecommuni- 
cations job, when executed, is terminated. 



MACRF=P 



Specifies that messages are to be trans- 
ferred to an MS destination queue by the PUT 
macro instruction. If this operand is 
omitted, the telecommunications job, when 
executed, is terminated. 



[DDNAME=ddname] 



PP 



ddname 

Is the name that appears in the DD statement 
associated with the data control block. If 
this operand is omitted and no value is pro- 
vided through an alternate source, the tele- 
communications job,„ when executed., is 
terminated. 



RECFM=G 
RECFM=S 



RECFM=R 



OE 



G, S, or R 

Specifies the work unit as follows: 

G -- message (the contents of the work area 
is considered to be a full message). 

S -- segment (the contents of the work area 
is considered to be a segment and it 
should fit into the buffer an even num- 
ber of times). 

R — record (the contents of the work area 

is considered to be a complete record). 

If this operand is omitted and the value not 
provided through an alternate source, 
RECFM=S is assumed. 



-+- 



[TRMAD=relexp] 



PP 



relexp 

Is the symbolic address of a user-provided 
area to contain the terminal table entry 
name. The length of the area must be equal 
to, or larger than, the maximum size termi- 
nal name or process queue name used. If 
this operand is omitted, the telecommunica- 
tions job, when executed, is terminated. 
When a PUT macro instruction is issued, the 
destination terminal name must be provided 
at the specified address. The name must be 
defined in a terminal table entry within the 
message control program. 



Figure 4. Keyword Operands for the Main Storage Destination Queue DCB 
Macro Instruction 
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Examples ; 

1 



A DCB macro instruction that defines 
the parameters of a data control block 
associated with a main storage process 
queue (see Figure 3 above). 



Note : For optimum performance, the 
message control program should always 
attempt to read ahead to keep one full 
work unit ready to be transferred in 
response to a GET. To achieve this, 
the BUFRQ operand should specify twice 
the number of buffers required to hold 
a single work unit. For example, a 
message of 2 00 data characters would 
require three 100-character buffers 
(200 data characters plus 76 charac- 
ters of QTAM control information) . 
The BUFRQ operand, in this case, 
should specify six buffers. 



r t t 

Name | Operation] Operand 

+ _1 

|DDNAME=PRCIN, 

jDSORG=MQ, 

|MACRF=G, 

J BUFRQ= 6 , SOWA=3 , 

JRECFM=G, 

|TRMAD=SOURCE, 

I SYNAD=ERROR 




PRCPROG 



SUBRTN1 



SUBRTN2 



GET QUEUE1 E0DAD=SUBRTN1 



GET QUEUE2 EODAD=SUBRTN2 



GET QUEUE 3 EODAD=PRCPROG 



In this situation,, if all the queues are 
empty, this process program loops continu- 
ally, relinquishing control only for I/O 
interrupts. 

It is suggested that the user issue some 
sort of wait before completing the loop. 
This might be accomplished by issuing an 
SVC STIMER for 3 milliseconds or so to 
allow the higher priority partition to get 
control., This will allow the message con- 
trol program to process at least one mes- 
sage before giving control back to the pro- 
cessing program. 

If this GET-EODAD loop is absolutely 
necessary, then the jcb in which it occurs 
must be in the lowest priority job in the 
system. 



j 



A DCB macro instruction that defines 
the parameters of a data control block 
to govern response message transfer 
(see Figure 4 above) . 



Name 



h 

| PPMQOUT j DCB 

I I 

I I 

I I 

L L 



| Operation j Operand 



| DDNAME=PRCOUT, 

j DSORG=MQ , MACRF= P , 

| RECFM=G, 

I TRMAD=DESTN 



._J 



EODAD Routine 

The EODAD operand of the DCB for the 
main storage process queue allows the user 
to specify a routine that will receive con- 
trol when a GET is issued for that queue 
and there is no message there. This rou- 
tine may do some processing and then 
attempt to get messages from some other 
queue. For example: 



HANDLING THE MESSAGE CONTROL PROGRAM 
INTERFACE 



QTAM provides macro instructions to handle 
the interface between the message process- 
ing program and the message control pro- 
gram- These macro instructions have the 
following functions: 

• Initializing and activating (OPEN macro 
instruction) 

• Deactivating (CLOSE and CLOSEMC macro 
instruct ions ) 

Initialization and activation of the 
interface to the message control program is 
accomplished by issuing an OPEN macro in- 
struction for the MS process queue (s), and 
if response messages are to be generated, 
for the MS destination queue. The OPEN 
routine performs the initialization func- 
tions that are necessary to activate the 
interface. No QTAM macros (including OPEN, 
CLOSE, GET„ and PUT) may be processed 
before the DCB for the direct access device 
message queue has been opened or after it 
has been closed. After the MS process and 
MS destination queues have been opened,, the 
transfer of data to and from the message 
processing program can commence. 
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When not required for further opera- 
tions, the MS process and MS destination 
queues should be deactivated. The CLOSE 
macro instruction accomplishes this by 
removing the queues from active use. The 
interface to the message control program is 
effectively destroyed, and no further mes- 
sages may be obtained from the MS process 
queue or placed on the MS destination 
queue. 

The deactivation of the MS process and 
MS destination queues can be performed in a 
special deactivation routine within the 
message processing program. This special 
routine can be entered as the result of a 
message received from a terminal operator 
directing that termination functions be 
performed. The analysis routine is coded 
to recognize this message (by a unique 
character indicating the message-type) as 
one requiring the execution of the deacti- 
vation routine. Linkage is established to 
the deactivation routine, which includes 
the necessary CLOSE macro instructions and 
instructions to perform other required ter- 
mination functions. 



OPEN Macro Instruction 



The data control blocks for MS process 
queues must be opened before the message 
processing program can issue GET instruc- 
tions to receive messages from the queue. 
The MS destination queue must be opened 
before the message processing program can 
PUT response messages to any destination. 
The OPEN macro instruction causes the 
initialization of the message control pro- 
gram interface to be completed. 

All data control blocks in the message 
processing program can be opened collec- 
tively with one OPEN or opened separately 
by individual OPEN macro instructions. 



dcbjL 



bol" is optional. If included, it 
becomes the name of the first instruc- 
tion generated by OPEN. 



The address of the data control block 
to be opened. If register notation is 
used, the register must contain the 
address. 

INPUT 

Specifies that this data set can be 
used for input. INPUT should be spec- 
ified for MS process queue data sets. 

OUTPUT 

Specifies that this data set can be 
used for output. OUTPUT should be 
specified for MS destination data set. 

y.F=L 

Causes creation cf a parameter list 
based on the OPEN operands. No 
executable code is generated. The 
user must specify this form of the 
OPEN with his program constants. The 
parameters in the list are not used 
until the problem program issues an 
OPEN (or CLOSE) macro with an MF=(E„ 
listname) operand referring to the 
list (see following text). The name 
specified in the name field of the 
OPEN macro becomes the name assigned 
to the parameter list. 

MF= (E, listname) 

Causes execution of the OPEN routine, 
using the parameter list referred to 
by "listname. " This list was created 
by a macro having the MF=L operand 
specif ied„ as described previously. 
Parameters specified through a macro 
having an MF= (E«, listname) operand 
override corresponding parameters in 
the list. An OPEN macro with the 
MF= (E, listname) operand can also refer 
to a parameter list created by a CLOSE 
macro with an MF=L operand. 



r t t 

| Name | Operation | Operand 

|. + 4 

[symbol] j OPEN | ( (dcb ± , ("INPUT 1 ,)... ) 

I j \ LoutputJ / 



[~,MF=L "I 

|_,MF=(E, listname)J 



L J. -L J 

symbol 

Either the name of the first instruc- 
tion generated by OPEN or the name of 
a parameter list created by OPEN. If 
the MF=L operand is specified, "sym- 
bol" must be included. It becomes the 
name of the parameter list. If no MF 
operand is specified, or the MF=(E, 
listname) operand is specified, "sym- 



CLOSE Macro Instruction 



The CLOSE macro instruction is used to 
deactivate the interface between the mes- 
sage processing program and the message 
control program. After the MS process 
queue has been closed, no further messages 
can be obtained from it for processing. 
Similarly, after the MS destination queue 
has been closed, no further response mes- 
sages can be placed on it. When a CLOSE is 
issued, main storage and subroutines 
acquired at open time are released; fields 
in the data control block that were ini- 
tialized at open time are cleared. 
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r t t 

| Name | Operation | Operand 



I- + 

| [symbol] j CLOSE 

I I 
I I 
I I 

L X 



| (ldcb lf ,}...) 



I [",MF=L "I | 

j L,MF=(E f listname)J j 

-X J 



symbol 

Either the name of the first 
tion generated by CLOSE or th 
a parameter list created by C 
the MF=L operand is specified 
bol" must be included. It be 
name of the parameter list, 
operand is specified, or the 
MF= (E, listname) operand is sp 
"symbol" is optional. If inc 
becomes the name of the first 
tion generated by CLOSE. 



instruc- 
e name of 
LOSE. If 

sym- 
comes the 
If no MF 

ecif ied, 
luded, it 
instruc- 



dcb ± 



The address of the data control block 
to be closed. If register notation is 
used, the register must contain the 
address. 



queue. Even though the messages are 
received from (and sent to), remote termi- 
nals via communication lines, the program- 
mer uses GET/PUT macro instructions for 
obtaining and sending messages. A QTAM 
message control program performs the 
device-dependent input/output operations 
for the message processing program. 

The main connectors between a message 
control program and a message processing 
program are the MS process and MS destina- 
tion queues. After the MS process queue 
has been defined and opened, a message is 
obtained from this queue by issuing a GET 
macro instruction. Once obtained, the mes- 
sage is analyzed and processed as required 
by the application. If a response message 
is generated, it is placed on the MS 
destination queue (after it has been 
defined and opened) by a PUT macro instruc- 
tion. The message control program then 
transfers the message to the appropriate 
DASD destination queue,, and finally sends 
the message to the remote terminal. 



MF=L 

Causes creation of a parameter list 
based on the CLOSE operands. No 
executable code is generated. The 
user must specify this form of the 
CLOSE with his program constants. The 
parameters in the list are not used 
until the problem program issues a 
CLOSE (or OPEN) macro instruction with 
an MF=(E, listname) operand referring 
to the list (see following text). The 
name specified in the name field of 
the CLOSE macro becomes the name 
assigned to this parameter list. 

MF=(E, listname) 

Causes execution of the CLOSE routine 
by using the parameter list referred 
to by "listname." This list was 
created by a macro having the MF=L 
operand specified, as previously 
described. Parameters specified 
through a macro having an MF=(E, 
listname) operand override correspond- 
ing parameters in the list. A CLOSE 
macro with the MF= (E, listname) operand 
can also refer to a parameter list 
created by an OPEN macro with an MF=L 
operand. 



OBTAINING MESSAGES AND PLACING RESPONSE 
MESSAGES 



QTAM provides the message processing pro- 
gram user with facilities for obtaining 
messages for processing and placing 
response messages on a DASD destination 



GET Macro Instruction 



GET obtains the next sequential work unit 
from the MS process queue indicated by the 
first operand. This operand is the name of 
the data control block associated with the 
KS process queue. The user specifies in 
the DCB macro instruction for the MS pro- 
cess queue,, the work unit with which he is 
operating (message segment, record, or com- 
plete message) . 

If the user specifies "segment" in the 
DCB, the work area must be large enough to 
accommodate an entire segment. Thus, for a 
buffer of 100 bytes, the work area must be 
at least 8 2 bytes. 

Maximum text segment = buffer size 
- size of text prefix = 78 

Work area size = maximum text segment 
+ work area prefix = 82 

If all the data in a segment cannot be 
accommodated in a work area, the remaining 
data is lost. There is no advantage in 
defining a work area cf greater size,, since 
no more than one text segment is trans- 
ferred into the work area for each GET. 

If the EOT character happens to be the 
last character in the message, an addition- 
al buffer with no data in it will be car- 
ried through the LPS with the other buffers 
for that message. If the user has speci- 
fied segment in the DCB and issues a GET 
for that data set, this empty buffer will 
be placed in the work area. This condition 
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can be detected by checking the first two 
bytes of the GET/PUT prefix of that segment 
for a count of four. 

If the user specifies "message" in the 
DCB, the data is transferred until the work 
area is full or the entire message is 
moved, whichever occurs first. For a given 
application, if the size of a message is 
known, the work area size should be set 
equal to this value. If the work area can 
not accommodate the full message, the 
remaining data is moved into the work area 
when the next GET is issued. Since a mes- 
sage is the logical unit being considered* 
the question of whether the work area 
should be smaller, equal to, or greater 
than a segment (buffer) size is not 
relevant. 

If the user specifies "record" in the 
DCE, the message data is moved into the 
work area until one of the following 
occurs : 

1. EOS, new line (NL) , carriage return 
(CR), or line feed (LF) is encoun- 
tered. (Data is transferred up to and 
including the first of these 
characters. ) 

2. An entire message has been 
transferred. 

3. The work area has been filled. 



the source terminal tc be placed in the 
area specified by the TRMAD keyword operand 
of the DCB macro instruction for the MS 
process queue. If a processing program 
puts the work unit in a process queue, 
zeros are placed in the user-specified 
area. If the work unit has been received 
over a switched line cr a nonswitched line 
with the Auto Poll feature, GET causes the 
name of the source terminal to be placed in 
the user-specified area only if the SOURCE 
macro instruction is included in the mes- 
sage control program LPS section that 
governs that terminal. If the SOURCF macro 
instruction has not been included, GET 
causes zeros to be placed in the user- 
specified area. (See the IBM System/360 
Operating System; QTAM Message Control 
Program publication.) 



GET uses the first four bytes in the 
user-specified work area to record informa- 
tion about the work unit. The first two 
bytes of the four-byte prefix (called the 
GET/PUT prefix), contain the number of 
characters in the work unit. The third 
byte identifies the type of segment or 
record (see Figure 5). As shown in the 
figure, all completed messages are identi- 
fied by a one in bit position 6. The last 
byte of the four-byte prefix is not modi- 
fied by QTAM. The user's message data 
starts with byte five of the work area. 



Since the logical unit considered is a 
record, the size of the work area should 
defined to accommodate a complete record. 



be 



When "record" has been specified in the 
DCB, the record must have been translated 
to EBCDIC in the Receive group cf the LPS. 

The synchronous error exit (SYNAD) will 
be taken, if specified, whenever any of the 
three forms of the GET macro is completed 
with data remaining in the buffers. 

The second operand is the address of the 
work area into which the work unit is to be 
placed. The user must define this work 
area in his problem program, and the size 
of the work area is specified in the SOWA 
keyword operand of the DCB macro instruc- 
tion for the MS process queue. 

If there is no work unit on the MS pro- 
cess queue, and no user-written routine is 
provided for this situation, the message 
processing program in which the GET appears 
enters a wait state. A user-written rou- 
tine can be specified via the EODAD keyword 
operand in the DCB macro instruction for 
the MS process queue. 

If tne work unit has been received via a 
nonswitched line, GET causes the name of 



If t?ECFM=R is specified in the MS pro- 
cess queue DCB macro instruction,, the GET 
routine transfers to the work area all 
characters up to and including the first of 
the following characters: carriage return, 
line feed, new line,, cr end-of-block. 

r t t 1 

] Name | Operation] Operand | 

j. + + -i 

j [symbol] | GET J dcb,workarea | 

1 L X X J 

symbol 

The name of the macro instruction. 

deb 

The symbolic address of the data con- 
trol block associated with the NS pro- 
cess queue from which the processing 
program is to obtain a work unit. If 
register notation is used, the regis- 
ter must contain the address of the 
DCB. 

workarea 

The address of the user-defined area 
in which the work unit is to be 
placed. If register notation is used, 
the address of the work area must have 
been previously loaded into the regis- 
ter specified. 
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PUT Macro Instruction 



The PUT macro instruction causes the pro- 
cessed message, message segment, or record 
to be transferred from the work area speci- 
fied to an MS destination queue. The mes- 
sage control program then transfers the 
work unit to the appropriate DASD destina- 
tion queue. Before issuing a PUT, the user 
must insure that the name of the terminal 
(to which the work unit is being sent) is 
in the location specified by the TRMAD key- 
word operand in the DCB macro instruction 
for the MS destination queue. Data 
transfer starts with the fifth byte of the 
work area. 

Prior to issuing a PUT, the user must 
also place the necessary information in the 
four-byte GET/PUT prefix. The length of 
the work unit to be transferred (including 
the four bytes in the prefix) must be spec- 
ified in bytes one and two, and the type of 
work unit must be specified in byte three 
(see Figure 5) . The fourth byte may con- 
tain a priority to be associated with the 
message. The value for this priority is 
chosen in the same way as for messages 
originating at remote terminals. 

The PUT macro instruction is concerned 
with one of three logical units, i.e., seg- 
ment, message, or record. 

If the user specifies "segment" in the 
DCB, the data will be transferred from a 
work area to a buffer. If the work area is 



larger than the buffer, an error code of 
X'10* is set in register 15, right- 
adjusted,, and no data is transferred. If 
the work area is siraller than the buffer, 
the buffer will not be completely filled 
and the extra space wasted. It is recom- 
mended that the same relationship exist 
between work area size and buffer size as 
with the GET segment. If the segments are 
not in correct sequence, that is„ a segmtut 
with EOM does not come before a header seg- 
ment, an error code of X'UO' is set in reg- 
ister 15, right-adjusted. 



If the user specifies "message" in the 
DCB, the contents of the work area are con- 
sidered to be a full message. If the work 
area is larger than the buffer^, the con- 
tents of the work area will be transferred 
to several buffers. If the work area is 
smaller than a buffer, space is wasted 
because the partially filled buffer is 
transmitted. The size of the work area 
should therefore be defined to accommodate 
a single message. 

If the user specifies "record" in the 
DCB, the contents of the work area are con- 
sidered to be a complete record. PUT does 
not check EOB , line feed (LF),, new line 
(NL), or carriage return (CR) to delimit 
the record. If the work area is larger 
than the buffer, the contents of the work 
area are transferred to several buffers. 
If the work area is smaller than the buf- 
fer, the buffer is filled in with other 
message blocks by succeeding PUT macros. 



(Bytes 1 and 2) 
Number of characters in the unit 
(including the four-byte user prefix) 


(Byte 3) 
work unit type 


(Byte 4) 
priority 



Third Byte Contents 


RECFM = G 
(complete messages) 


RECFM = S 
(message segments) 


RECFM = R 
(message record) 


X'OO' 




Multiple- segment message. This 
segment contains a header. 


Multiple- block message. This 
block contains a header. 


X'OT 




Multiple- segment message. This 
is an intermediate segment con- 
taining text only. 


Multiple- block message. This 
is an intermediate block con- 
taining text only. 


X'02' 


complete messages 


Single- segment complete message. 


Single- block complete message. 


X'03' 




Multiple- segment message. This 
is the last segment and contains 
text only. 


Multiple- block message. This 
is the last block and contains 
text only. 



Figure 



Meaning of the Bytes in the GET/PUT Prefix 
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The format of a record being PUT from a 
message processing program must be consid- 
ered in defining the send sections of the 
LPS in the message control program. For 
example, if the TIMESTMP, DATESTMP, or 
SEQOUT macro instructions are used in the 
SENDHDR section of the LPS, the number of 
bytes required by these macros must be 
reserved at the beginning of the record 
before issuing the PUT. These fields must 
be filled with idle characters (X'17* in 
EBCDIC) . Any other macro instructions in 
the SENDHDR section of the LPS will bypass 
these idle characters in scanning for the 
beginning of the header field. 

Note also that if a message is to be PUT 
just as it was received by a GET, the 
SENDHDR section of the LPS should not 
include macro instructions that refer to 
the header portion of the message. Alter- 
natively, if the header must be worked on 
in the SENDHDR section, those fields that 
were processed in the RCVHDR section prior 
to the GET should be overlaid with idle 
characters before the subsequent PUT. 

Another point to be noted is that an EOA 
(end of address) sequence should not be 
generated in a header by a message process- 
ing program prior to a PUT. If required. 



the EOA should be placed in the header by 
the SENDHDR portion of the LPS after execu- 
tion Of any TIMESTMP* DATESTMP,, Or SEQOUT 
macro instructions. 

A message cannot be routed to multiple 
destinations or a distribution list entry 
by a PUT macro instruction. 

r t t 1 

| Name | Operation] Operand | 

V + f ^ 

] [symbol] | PUT ] dcb„workarea | 

L JL X J 

symbol 

The name of the macro instruction. 

deb 

The symbolic address of the data con- 
trol block associated with the MS 
destination queue. If register nota- 
tion is used, the register must con- 
tain the address of the DCB. 

workarea 

The address of the user-defined area 
from which the work unit is to be 
transferred. If register notation is 
used, the register must contain the 
address. 
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NETWORK CONTROL FACILITIES 



The user may find it advisable during pro- 
cessing to examine control information used 
by QTAM and to make necessary modifications 
to the system. QTAM provides a set of 
macro instructions for this purpose. The 
macro instructions enable the user to 
dynamically: 

• Activate or deactivate a particular 
line in a communication line group 
(STARTLN and STOPLN macro 
instructions) . 

• Examine and modify terminal-table 
entries (COPYT, CHNGT, and RELEASEM 
macro instructions) . 

• Examine and modify polling lists (COPYP 
and CHNGP macro instructions) . 

• Examine queue control blocks for DASD 
destination and process queues (COPYQ 
macro instruction) . 

• Retrieve for retransmission messages 
previously sent to terminals (RETRIEVE 
macro instruction). 



nal and the CPU could be the same individ- 
ual. This centralizes the overall control 
of the telecommunications system. However, 
the user can designate any terminal in the 
system as the control terminal. 

Some of the macro instructions discussed 
in this section may also be issued in the 
message control program. Execution of 
these macro instructions in the message 
control program must cccur between the CPEN 
and ENDREADY macro instructions. 

WARNING : It is possible that the mes- 
sage control program might access the 
terminal table, polling list, queue con- 
trol block, or threshold counters at the 
same time that the processing program is 
executing a copy or change macro in- 
struction. Accordingly,, the line should 
first be stopped by issuing a STOPLN 
macro instruction. The change or copy 
macro instruction is then issued and 
followed by a STARTLN to restart the 
line. 



In order to dynamically examine and 
modify the status of the system, these 
macro instructions must be used in a mes- 
sage processing program. 

Routines containing the examination and 
modification macro instructions can be 
executed at any time during the operation 
of the system as the result of a message 
sent to the message processing program by a 
terminal operator. Such messages are 
handled in the same manner as any other 
message that enters the system from a 
remote terminal. In other words, the mes- 
sage control program performs the necessary 
control functions and routes the message to 
the appropriate message processing program. 
The message processing program is specified 
as the destination in the message header. 
At some prespecified position in the mes- 
sage (for example, in the header or in the 
first position of the text), a message-type 
character is specified that identifies the 
message as one requiring the execution of 
an examination or modification routine. 
The analysis routine of the message pro- 
cessing program can be written to recognize 
this message-type character and branch to 
the desired routine. 

The terminal sending such a message is 
usually located on the same premises as the 
CPU and is designated as the "control'' ter- 
minal. The operator of the control termi- 



LINE ACTIVATION AND DEACTIVATION 



Normally* the lines in a line group are 
automatically prepared for message trans- 
mission when the line group is opened in 
the message control program. When issued 
in a message processing program,, the STOPLN 
and STARTLN macro instructions enable the 
user to dynamically deactivate and reac- 
tivate a specific line (or all the lines) 
within the line group at any point during 
the operation of the system. 

STOPLN is used to effect a temporary 
deactivation of a specific line when the 
line is expected to be reactivated by a 
subseauent STARTLN macro instruction. 



Stop Line (STOPLN) Macro Instruction 



STOPLN removes a communication line from 
active use. This macro instruction causes 
operations on the designated line to stop 
immediately after completion of any message 
currently being received or transmitted. 
Transmission of any messages remaining in 
the queue for the line resumes when a 
STARTLN macro instruction reactivates the 
line. 
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) Name | Operation | Operand | 
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| [symbol] | STOPLN | termname, jrln\ | 
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symbol 

Is the name of the macro instruction. 

termname 

Is the name of any terminal in the 
line group, but not necessarily the 
name of a terminal on the line being 
stopped- If register notation is 
used, the register must contain the 
address of the data control block for 
the line group. It cannot contain the 
terminal name. 

If an invalid terminal name is speci- 
fied, an error code of X* 20* „ right- 
adjusted, is set in register 15. If 
the DCB for the line group has not 
been opened, an error code of X'01' is 
set in register 15. In either case, 
the STOPLN has no effect. 



rln 



Is the relative line number (within 
the line group) of the line to be 
deactivated. If register notation is 
used, the general register specified 
must contain the relative line number 
in binary form. If an invalid rln is 
specified, a code of X*08', right- 
adjusted, is set in register 15. 



In each of the preceding cases, if poll- 
ing is used, the presence of an active 
polling list is a prerequisite for message 
transmission. (An active polling list is 
one in which the second byte of the list is 
a non-zero character — this character is 
initialized as a 1 and can be changed by 
the CHNGP macro instruction.) If STARTLE 
is used, polling or enabling of input lines 
begins after the execution of that macro 
instruction. Initial polling or enabling 
of input lines in a line group begins when 
the line group is opened in the message 
control program. If activation of a line 
group was deferred by inclusion of the IDLE 
operand in the OPEN macro for the line 
group, a STARTLN macro must be issued to 
activate the lines. 

An attempt to initiate input/output 
operations on a line on a control unit that 
is not operational will result in the fol- 
lowing sequence of system error messages: 

IEC8 04I CONTROL UNIT NOT OPERATIONAL 
IEC8 04A REPLY CONT OR POST 

If CONT is replied, the operation will be 
retried. If the action taken is not suc- 
cessful, the series of messages will be 
issued again. If POST is replied,, the line 
will be ignored until a STARTLN macro is 
issued to that line, or a STARTLN control 
message for that line is sent. If the con- 
trol unit is still not operational, the 
entire sequence will be repeated. As with 
any WTOR message „ the control program is in 
the wait state until the reply is received. 



ALL 



Specifies that all lines in the line 
group are to be deactivated. 



If no errors were detected in the STOPLN 
macro, register 15 contains all zeros. 



r r t 1 

| Name | Operation ] Operand | 

] [symbol] | STARTLN j termname, /rln} | 
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symbol 

Is the name of the macro instruction. 



Start Line (STARTLN) Macro Instruction 



STARTLN can be used to: 

1. Allow message transmission to, resume 
on a particular line in a communica- 
tion line group. 

2. Allow message transmission to resume 
on all lines in a communication line 
group. The user must have previously 
opened the line group in the message 
control program. 

If a line is deactivated by a STOPLN 
macro instruction, STARTLN must be issued 
before message transmission on that par- 
ticular line can resume. 



termname 

Is the name of any terminal in the 
line group, but not necessarily the 
name of a terminal on the line being 
started. If register notation is used 
the register must contain the address 
of the data control block for the line 
group. It cannot contain the terminal 
name. If an invalid terminal name is 
specified, an error code of X'20', 
right-adjusted, is set in register 15. 
If the DCB for the line group has not 
been opened, an error code of X'01' is 
set in register 15. In either case, 
the STARTLN has no effect. 



rln 



Is the relative line number,, within 
the line group,, cf the line to be 
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ALL 



reactivated. If register notation is 
used, the general register specified 
must contain the relative line number 
in binary form. If an invalid rela- 
tive line number is specified, a code 
of X'08', right-adjusted, is set in 
register 15. 



Specifies that all lines in the line 
group are to be activated. 



If no errors were detected in the STARTLN 
macro, register 15 contains all zeros. 



EXAMINING AND MODIFYING THE TERMINAL TABLE 



QTAM provides macro instructions that 
enable the user to examine and dynamically 
change the control information contained in 
a terminal- table entry. 

The COPYT macro instruction causes the 
contents of a specified terminal-table 
entry to be copied into a work area. This 
macro instruction can be used in conjunc- 
tion with the CHNGT macro instruction, 
which substitutes a new terminal-table 
entry for a superseded one. The user 
issues a COPYT, examines the information, 
changes it if necessary, and issues a 
CHNGT. 

The user can also change terminal-table 
information via the RELEASEM macro instruc- 
tion. RELEASEM causes the intercept bit 
for a specified terminal-table entry to be 
set to 0. All messages intercepted for 
that terminal are then transmitted to the 
terminal. 



Copy Terminal-Table Entry (COPYT) Macro 
Instruction 



COPYT moves the information contained in a 
specified terminal-table entry into a des- 
ignated work area. (The information copied 
into the work area remains in the same form 
as in the terminal table: binary fields 
remain binary and EBCDIC fields remain 
EBCDIC.) The terminal-table entry can be 
either a single-terminal, group-code, dis- 
tribution-list, or process program entry. 
Formats for each of these entries are shown 
in Appendix A of the OS QTAM Message Con- 
trol Program publication. 

r t t T 

I Name | Operation | Operand ] 
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| [symbol] | COPYT | termname,workarea | 
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symbol 

Is the name of the macro instruction. 

termname 

Is the name of the terminal whose 
terminal- table entry is to be copied. 
If register notation is used, the gen- 
eral register designated must contain 
the address of a location containing 
the name of the terminal. The field 
containing the name must be "n" bytes 
in length, where "n" equals or exceeds 
the longest name of any terminal-table 
entry. The name must be left-adjusted 
and must be padded with blanks to the 
length of the longest TERM entry in 
the terminal table. If an invalid 
terminal name is specified,, no data 
movement takes place; the routine 
linked by the COPYT macro instruction 
returns an error code of X* 20 ■ right- 
adjusted, in register 15. If no error 
is detected, register 15 contains 
zero. 

workarea 

Is the address of the area into which 
the information is placed. The first 
byte of the work area receives the 
first byte of data from the terminal- 
table entry. The maximum size of the 
work area is 252 bytes (the maximum 
size of a terminal-table entry) . If 
register notation is used, the general 
register designated must contain the 
address of the wcrk area. 



Change Terminal-Table Entry (CHNGT) Nacro 
Instruction 



CHNGT moves the information for a terminal- 
table entry from a designated work area to 
the terminal- table area allocated for that 
entry. CHNGT causes the entire contents of 
the superseded terminal-table entry,, except 
for the TSEQUIN and TSEQOUT fields, to be 
changed. The TSEQUIN and TSEQOUT fields 
are not changed because of the possibility 
that a message may be received between the 
time the entry is copied and the time it is 
changed. This would cause a sequence num- 
ber error to occur. In order to change the 
entire contents, including TSEQUIN and 
TSEQOUT w the user must precede the CHNGT 
macro with a STOPLN macro for the line on 
which the affected terminal is located. 

CHNGT is normally preceded by the COPYT 
macro instruction and instructions to 
examine and modify the contents of the 
copied terminal-table entry. The user must 
be certain that the new terminal-table 
entry contains all the information required 
for proper execution of QTAM. The informa- 
tion copied into the terminal table should 
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be formatted appropriately in binary or 
EBCDIC form. The format of the terminal- 
table entries and the information contained 
in each field are contained in Appendix A 
of the OS QTAM Message Control Program 
publication. 

r t t T 

| Name | Operation | Operand | 
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| [symbol] JCHNGT | termname, workarea 1 
l j. j. j 

symbol 

Is the name of the macro instruction. 

termname 

Is the name of the terminal whose 
terminal-table entry is to be 
replaced. It must be the same as a 
name that appears in the name field of 
a TERM, PROCESS, or DLIST macro in- 
struction. If register notation is 
used, the address of a location con- 
taining the name must be in the gener- 
al register designated. The field 
containing the name must be "n" bytes 
in length, where "n" equals or exceeds 
the longest name of any terminal-table 
entry. The name must be left-adjusted 
and must be padded with blanks to the 
length of the longest TERM entry in 
the terminal table. 

If an invalid name is specified, the 
routine generated by CHNGT returns an 
error code of x'20', right-adjusted, 
in register 15. QTAM subsequently 
disregards the new terminal-table 
entry and continues to use the old. 

workarea 

Is the address of the area from which 
the information is moved. If register 
notation is used, the general register 
specified must contain the address of 
the work area. If the new entry does 
not equal the size of the old entry,, 
no data movement takes place. An 
error code of X'10* is returned in 
register 15, and QTAM continues to use 
the old entry. 

If no errors were detected in the CHNGT 
macro, register 15 contains all zeros. 



The intercept bit is turned on (that is, 
set to one) by the INTERCPT macro instruc- 
tion in the LPS section of the message con- 
trol program. 

It should be noted that messages for 
this terminal that were intercepted and 
later released will not be transmitted 
immediately. The queue of messages for 
this terminal must be "primed" by having 
another message put on that queue. The 
presence of this message on the queue 
causes QTAM to attempt to contact the ter- 
minal. If the terminal is free,, the mes- 
sages on the queue are transmitted by 
priority. If the terminal is busy w the 
messages will not be transmitted at that 
time. 

r t t 1 
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symbol 

Is the name of the macro instruction. 

termname 

Is the name of the terminal that can 
now receive its intercepted messages. 
It must be the same as a name that 
appears in the name field of a TERM 
macro instruction. If register nota- 
tion is used„ the address of a loca- 
tion containing the name must be in 
the general register designated. The 
field that contains the name must be 
"n" bytes in length, where "n" equals 
or exceeds the longest name of any 
terminal-table entry. The name must 
be left-adjusted and must be padded 
with blanks to the length of the lon- 
gest TERM entry in the terminal table. 
If termname is invalid,, an error code 
of X*20*, right-adjusted, is set in 
register 15. If the line was never 
intercepted,, an error code of X*0 4 9 
will be returned in register 15. If 
RELEASEM is issued during a restart, 
an error code of X 8 02' ff right- 
adjusted, is set in register 15. 
RELEASEM should be issued until a 
normal return code is received. A 
normal return code indicates that the 
RELEASEM macro instruction is being 
executed. 



Release Messages (RELEASEM) Macro 
Instruction 



RELEASEM sets to zero the intercept bit in 
the terminal -table entry for the specified 
terminal. This results in the sending of 
all intercepted messages with that terminal 
as the destination; all suppressed messages 
are sent, as well as any new messages. 



EXAMINING AND MODIFYING POLLING LISTS 



QTAM provides macro instructions that 
enable the user to examine and modify the 
contents of the polling list for a line. 
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The COPYP macro instruction causes the 
contents of a specified polling list to be 
copied into a work area. This macro in- 
struction can be used in conjunction with 
the CHNGP macro instruction, which can sub- 
stitute a new polling list for a superseded 
one (the new list must be the same size as 
the old one). The user issues a COPYP, 
examines the information, changes it if 
necessary, and issues a CHNGP. CHNGP can 
also be used to stop or restart polling of 
the terminals on a line. 



area receives the first byte of data 
in the polling list. The size of the 
area necessary can be determined from 
the polling list format shown in 
Appendix A of the OS QTAM Message Con- 
trol Program publication. If register 
notation is used, the general register 
specified must contain the address of 
the work area. 

If no errors were detected in the COPYP 
macro, register 15 contains all zeros. 



Copy Polling List (COPYP) Macro Instruction 



Change Polling List (CHNGP) Macro 
Instruction 



COPYP causes the polling list fcr a speci- 
fied line to be copied into a user- 
designated work area- The format of the 
polling list is shown in Appendix A of the 
OS QTAM Message Control Program 
publication. 



symbol 

Is the name of the macro instruction. 

termname 

Is the name of any terminal in the 
line group, but not necessarily the 
name of a terminal in the polling list 
being copied. If register notation is 
used, the general register designated 
must contain the address of the data 
control block for the line group. It 
cannot contain the terminal name. 

If an invalid terminal name is speci- 
fied, an error code of X^O', right- 
adjusted, is set in register 15. If 
the DCB for the line group has not 
been opened, an error code of X'Ol* is 
set in register 15. In either case, 
the COPYP has no effect. 

rln 

Is the relative line number,, within 
the line group, of the line whose 
polling list is to be copied. If reg- 
ister notation is used, the user pre- 
viously must have placed the relative 
line number (in binary form) in the 
general register designated. If the 
rln specified is invalid, a code of 
X'08*, right-adjusted, will be set in 
register 15. 

workarea 

Is the address of the work area into 
which the polling list is to be 
copied. The first byte of the work 



CHNGP can either: 

1. Place a new polling list in the poll- 
ing list area for a specified line. 

2. Change the status of a polling list 
for a specified line. 
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| Name | Operation | Operand | 
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| [symbol] | COPYP | termname, rln, workarea | |-- 
l l jl J 



Name 



- T T 

| Operation] Operand 



[symbol] | CHNGP 



] termname, rln, 
j (workarea) 

j =co' V 

j(=C"l' ) 

.X 



symbol 

Is the name of the macro instruction. 

termname 

Is the name of any terminal in the 
line group,, but not necessarily the 
name of a terminal in the polling list 
being changed. If register notation 
is used, the general register desig- 
nated must contain the address of the 
data control block for the line group. 
It cannot contain the terminal name. 

If an invalid terminal name is speci- 
fied, an error cede of X'20* right- 
adjusted, is set in register 15. If 
the DCB for the line group has not 
been opened, an error code of X'01* is 
set in register 15. In either case, 
the CHNGP has no effect. 



rln 



Is the relative line number, within 
the line group, of the line whose 
polling list is to be modified. If 
register notation is used, the user 
previously must have placed the rela- 
tive line number (in binary form) in 
the general register specified. If 
the relative line number is invalid 
(the line group has no such line num- 
ber) an error code of X f 08", right- 
adjusted, is set in register 15. 
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workarea 

Is the address of the area that con- 
tains the new polling list. The first 
byte of the polling list area receives 
the first byte of data in the work 
area. If the new polling list does 
not equal the size of the old, no data 
movement takes place. An error code 
of X^O* is set in register 15. QTAM 
subsequently disregards the new poll- 
ing list and continues to use the old. 



=C0' 



Causes the second byte of the polling 
list be changed to a zero. This 
results in the deactivation of the 
polling list. No further messages are 
received until the list is 
reactivated. 



=C*1 



Causes the second byte of the polling 
list to be changed to a one. This 
results in the activation of the poll- 
ing list. QTAM begins polling the 
terminals on the line and accepting 
incoming messages. 

If no errors were detected in the CHNGP 
macro, register 15 contains all zeros. 



Copy Queue Control Blcck (COPYQ) Macro 
Instruction 



COPYQ places the contents of a QCB in a 
specified work area. The user indicates 
the QCB desired by specifying the name of a 
terminal or the naire cf a DASD process 
queue. If the name of a terminal is speci- 
fied, COPYQ places the QCB for the DASD 
destination queue associated with that ter- 
minal in the work area. If the name of a 
DASD process queue is specified, the QCB 
for the DASD process queue is placed in the 
work area. In both cases, the entire con- 
tents of the 32-byte QCB are provided. 
However, certain fields are used internally 
by QTAM routines and are not of concern to 
the user (see Figure 6). 



r t t 1 

| Name | Operation j Operand | 
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symbol 

Is the name of the macro instruction. 



EXAMINING QUEUE CONTROL BLOCKS 



Each terminal-table entry defined by a TERM 
or PROCESS macro instruction contains the 
address of the queue control block (QCB) 
for the DASD destination or DASD process 
queue on which outgoing messages are 
placed. QTAM uses the QCB for: 

1. Placing each message on its appropri- 
ate DASD queue. 

2. Maintaining information on the status 
of the queue. 

The COPYQ macro instruction enables the 
user to examine a QCB to ascertain the sta- 
tus of the DASD destination or DASD process 
queue associated with the QCB. 

Figure 6 shows the contents and relative 
displacement of each field in the QCB that 
is of interest to the user. After issuing 
a COPYQ macro instruction to copy the QCB 
into a user-specified work area, the user 
can determine the contents of the fields 
from which he needs information. For 
example, the user can determine the number 
of messages in the queue, or can use the 
address of the queue on the disk to 
retrieve a message (see the RETRIEVE macro 
instruction description) . 



termname 

Is the name of the terminal or DASD 
process queue whcse associated QCB is 
to be copied. Only the name of a 
single-terminal cr process program 
terminal- table entry can be specified, 
that is, the name specified in a TERM 
or PROCESS macro instruction. If 
specified,, no data movement takes 
place. If register notation is used, 
the address of a location containing 
the name must be in the designated 
general register. The field contain- 
ing the name irust be "n" bytes in 
length, where "n" equals or exceeds 
the longest name of any terminal table 
entry. The name must be left-adjusted 
and must be padded with blanks to the 
length of the longest TERM entry in 
the terminal table™ If an invalid 
termname is specified, a code of 
X'20* ff right-adjusted, is set in reg- 
ister 15. 

workarea 

Is the address of the area in which 
the contents of the QCB are placed. 
The area must be 32 bytes long (the 
size of the QCB). If register nota- 
tion is used, the general register 
specified must contain the address of 
the work area. 

If no errors were detected in the COPYQ 
macro, register 15 contains all zeros. 
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QFAC 



QRLN 



QDCB 



Is the relative record address of the next message to be read from this DASD 
queue; that is, the next message to be processed or transmitted. 

Is the relative line number of the line associated with this queue. (Field used 
only for a DASD destination queue.) 

Is the address of the data control block associated with this QCB. (Field used 
only for a DASD destination queue.) 



QSIZE 

Is the number of complete messages on this queue. 

QNASEG 

Is the relative record address on the DASD message queue data set where the header 
segment of the next message for this queue will be placed. 

QBACK 

Is the relative record address of the last message placed on this DASD queue. 

L . 

Figure 6. Format of Queue Control Block (QCB) 



RETRIEVING MESSAGES 



Retrieve Message Segment (RETRIEVE) Macro 
Instruction 



During the operation of a telecommunica- 
tions system, it may be necessary to 
retrieve a message that has already been 
placed on a DASD destination or DASD pro- 
cess queue. The RETRIEVE macro instruction 
is used to perform this function. 



For example, a terminal operator may 
misplace a message that was previously sent 
to his terminal. He can send a message 
(with a message processing program as the 
destination) requesting that the missing 
message be sent again. In the request mes- 
sage, he provides the name of his terminal 
and the sequence number of the message to 
be retransmitted. The message processing 
program uses the provided information to 
RETRIEVE the message from the DASD destina- 
tion queue that contains messages for that 
terminal. Subsequently, the message is 
retransmitted to the terminal via a PUT 
macro instruction. 



RETRIEVE transfers a message segment 
already placed in a DASD destination queue 
or DASD process queue to a user-provided 
work area. 

A message segment can be retrieved 
either by specifying the terminal name to 
which the message was sent, or by providing 
the relative record address of the message 
segment on the direct access storage 
device. In the first methods the input or 
output sequence nuirber must be specified. 
The relative record address in the second 
method is based on zero and reflects the 
position of the segment in relation to 
other segments on the storage device. In 
operation, the second method is faster. 

The most common implementation of the 
RETRIEVE macro instruction uses both of 
these methods. A terminal name and input 
or output sequence number are specified for 
retrieval of the first message segment. 
This segment contains the header prefix and 
header portion of the message. RETRIEVE 
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uses the input or output sequence number to 
find the desired message. When found, the 
segment containing the header prefix and 
message header is placed in the work area 
specified by the user. The header prefix 
(the first 24 bytes of the segment contain- 
ing the header 1 ) contains, in the MSLINK 
field, the relative record address of the 
next segment of the message. The user can 
load the contents of this field into a reg- 
ister and obtain the next segment by issu- 
ing a RETRIEVE macro that specifies the 
relative record address. Subsequent text 
segments can be retrieved by means of the 
relative record address found in the MSLINK 
field of the text prefix (first 14 bytes of 
the segment containing the text 1 ) in each 
previous segment. The last segment of a 
message can be detected by examining the 
seventh bit (X'02') of the status field 
(MSTATUS) in the buffer prefix. This bit 
is set on for the last segment cf each mes- 
sage. The formats of the header and text 
prefixes are shown in Appendix A of the OS 
QTAM Message Control Program publication. 
Figure 7 gives an example of the use of 
RETRIEVE. 



| Name | Operation (Operand 
j. + + . 

[ symbol ] | RETRIEVE 



Itermname 1 
(.(dasdaddr )/ , workarea , 

\i m \ 1 

|\OUT/, number „ 



I TYPE= 



§ 



i j. x J 

symbol 

Is the name of the macro instruction. 

termname 

Is the name of the destination point 
of the message segment to be re- 
trieved. This is the name specified 
in the TERM or PROCESS macro instruc- 
tion and included in the entry in the 
terminal table. The type cf entry 
referred to can be either a single- 
terminal, group-code, or process pro- 
gram entry. (The name of a distribu- 
tion list cannot be specified nor can 
the name of a process program entry 
that is defined with the EXPEDITE 
operand.) If this operand is speci- 
fied, the first segment of the message 
is retrieved. If register notation is 
used, the address of a location con- 
taining the name must be in the gener- 



^■When the segment was placed on the direct 
access queue, the first eight bytes of the 
32-byte header prefix (or of the 2 2-byte 
text prefix) were deleted. 



al register designated. The field 
that contains the name must be "n" 
bytes in length, where "n" equals or 
exceeds the longest name of any termi- 
nal table entry* The name must be 
left-adjusted and must be padded with 
blanks to the length of the longest 
TERM entry in the terminal table. If 
an invalid termname is specified, a 
return code of X*20* is placed in reg- 
ister 15. 

(dasdaddr) 

Is the parenthesized name or number of 
a register containing the relative 
record address of the message segment 
to be retrieved- The user must have 
previously placed the 3-byte record 
address in this designated register. 
If an invalid termname is specified, 
an error code of X*20*, right- 
adjusted,, is returned in register 15. 



workarea 

Is the address of the 
work area in which th 
is to be placed. If 
is used, the general 
fied must contain the 
work area. The work 
least the size of the 
in the disk initializ 
If an invalid relativ 
has been specified, a 
X , 02', right-adjusted 
register 15. 



user-provided 
e message segment 
register notation 
register speci- 

address of the 
area must be at 

record defined 
ation process, 
e record number 

return code of 
, is placed in 



IN 



Indicates that the "number" operand 
that follows specifies the input 
sequence number cf the message to be 
retrieved. If the "termname" operand 
is included,, either the IN or OUT 
operand and the "number" operand must 
be specified. If the "(dasdaddr)" 
operand is included, IN (as well as 
OUT and "number") must be omitted.. 



OUT 



Indicates that the "number" operand 
that follows specifies the output 
sequence number cf the message to be 
retrieved. If the "termname" operand 
is included, either the OUT or IN 
operand and the "number" operand must 
be specified- If the "(dasdaddr)" 
operand is included, OUT (as well as 
IN and "number") must be omitted. If 
the sequence number is invalid, an 
error code of X°40", right-adjusted,, 
is set in register 15. 

number 

Is the input or output sequence number 
of the message tc be retrieved. If 
the "termname" operand is included, 
the "number" operand must be speci- 
fied. If the "(dasdaddr)" operand is 
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included, the "number" operand must be TYPE=S 



omitted. If the sequence number is 
invalid,, an error code of X* 40', 
right-adjusted, is set in register 15. 
This number must be in binary form. 
Messages sent from the telecommunica- 
tions control or alternate terminal 
may not be retrieved by sequence 
number. 



Specifies that the message segment is 
to be retrieved using the terminal 
name-sequence number method. 



TYPE=D 

Specifies that the message segment is 
to be retrieved using the relative 
record address method. 



r t t 

| Name | Operation | Operation 



j Comments 



1. + 

|RETRMSG | RETRIEVE 


_ + 

| BOS , CNSLPRT, IN , 121 


+ 

,TYPE=S | Retrieves the first segment of a message 
jwith input sequence number 121, destined 
| f or the Boston terminal, and places the 
| segment in the CNSLPRT area. The seg- 
|ment contains the QTAM shortened header 
j prefix and the message header. 




|LA 


|5,CNSLPRT 








j Loads the address of the user's work 
| area into general register 5. 




| USING 


|IECKPREF+8,5 








(Establishes addressability with respect 
jto the DSECT for the QTAM header prefix. 




1 • 










| Processing of the header segment accord- 
ling to the current application. 


|TEST 


|TM 
|BO 


| MSTATUS , 2 
|OUT 








| Tests the status field of the buffer 
(prefix to determine if this is the last 
(segment of the message. 

j If yes, branches out of the loop. 




|MVC 


|LINKINFO+l(3] 


„ MSLINK 


(Moves the MSLINK field of the QTAM head- 
ier prefix (containing the address of the 
(next segment of the message) into an 
j area from which it can be loaded into a 
| general r egi ster . 




|L 


|4,LINKINF0 








| Loads the contents of MSLINK into gener- 
j al register 4. 




| RETRIEVE 


| (4) ,CNSLPRT,TYPE= 


=D 




(Retrieves the next segment of the mes- 
jsage and places it in the work area. 




1 • 










(Processing of the text segment according 
jto the current application. 




|B 


|TEST 








(Loop back to test for last segment. 


|OUT 


| PREFIXD 










(Generates the DSECT of the QTAM header 
j prefix. 


r 

(This 
| area 


example assumes that each segment is 
may be reused in retrieving the next 


processed after retrieval so that the work 
segment. 



Figure 7. Example of the Use of the RETRIEVE Macro Instruction 
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CHECKPOINTING THE MESSAGE CONTROL PROGRAM 



QTAM provides the facility for writing 
checkpoint records either at specified 
intervals of time or at certain points in 
one or more processing programs (see the OS 
QTAM Message Control Program publication),. 

The checkpoint records contain the in- 
formation necessary to record the status of 
the queues and the telecommunications net- 
work. In particular, the checkpoint record 
includes the polling lists, the terminal 
table, disk pointers and status information 
associated with each queue, and disk point- 
ers and status information associated with 
each line. Note that the data in the buf- 
fers is not included in the checkpoint 
record. Two such checkpoint records are 
maintained in the checkpoint data set along 
with a pointer to the most recent record. 
The format of the checkpoint records is 
shown in Appendix A. 

The user may specify that checkpoint 
records are to be taken at desired points 
in the processing programs by: 



It should be noted that the CKREQ macro 
instruction cannot be issued in the message 
control program. The CPINTV and CKPART 
operands may not both be specified; if both 
are specified, CPINTV will take precedence 
and CKPART will be ignored. If the CPINTV 
keyword is used and the processing program 
issues a CKREQ macro instruction.,, the 
checkpoint records will be taken at the 
intervals of time specified by the CPINTV 
operand. 



r t t 1 

| Name | Operation ] Operand | 

] (name) ] CKREQ ] | 

i x X J 



name 



Is the name of the first instruction 
generated by CKREQ. 



1. Allocating space on the DASD for the 
checkpoint data set. 

2. Defining the data set. 

3» Opening and closing the data set. 

4. Using the CKPART operand in the 

TERMTBL macro instruction in the mes- 
sage control program and issuing a 
CKREQ macro instruction in each pro- 
cessing program that is to be used in 
determining when to take the check- 
point records. 

The control program is checkpointed when 
all the required partitions have issued the 
CKREQ macro instruction. For instance, if 
CKPART=2 is specified in the TERMTBL macro 
instruction, and Processing Program 1 
issues a CKREQ macro instruction,, it will 
go into a wait state until some other par- 
tition also issues a CKREQ macrc instruc- 
tion. At that point the checkpoint will be 
taken. This puts both of these processing 
programs in synchronization with the mes- 
sage control program. The processing pro- 
grams know the exact circumstances at the 
checkpoint and can take steps tc guard 
against duplicate messages following a 
restart. 



When the correct number of CKREQ macro 
instructions have been issued* checkpoint 
records are written on a checkpoint data 
set maintained on a direct access storage 
device (DASD) . A new checkpoint record is 
written over the oldest existing record and 
the pointer is updated to reflect the most 
recent record. Should a system failure 
occur during checkpoint itself, restart may 
still be accomplished using the alternate 
checkpoint record. 

Restart allows the user to reestablish 
the queues and the telecommunications net- 
work to its status just prior to the last 
checkpoint. 

For information on allocating space for 
the checkpoint data set*, defining,, opening, 
and closing the checkpoint data set, and 
restarting the message control program,, see 
the OS QTAM Message Ccntrol Program 
publication. 



Note ; If checkpointing is specified at 
time intervals (CPINTV operand in TERMTBL 
macro) , no additional instructions are 
necessary in the processing programs; 
checkpointing is thus made independent of 
the processing programs. 
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DEACTIVATING THE TELECOMMUNICATIONS SYSTEM 



In order to terminate operation of the 
telecommunications system, the communica- 
tion line group, checkpoint, and direct 
access message queues data sets must be 
closed. Before they may be closed,, all 
message traffic in the system must cease. 
To accomplish this, the user issues a 
CLOSEMC macro instruction in a user-written 
termination routine. CLOSEMC controls and 
monitors line activity and checks the sta- 
tus of all data sets opened in the message 
processing programs. When all data sets 
opened in the message processing programs 
are closed, and line activity has ceased, 
the routine returns control to the user to 
permit him to close the line group and mes- 
sage queues data sets. (See Appendix D for 
a sample program.) Deactivation of the 
system proceeds in the following manner. 

When the system is to be deactivated, a 
CLOSEMC macro instruction must be issued in 
a program other than the message control 
program. A recommended procedure is to 
send a special message to a process queue 
from which a message processing program, 
containing a user-written termination rou- 
tine, may obtain the message. 

This termination routine should do the 
following: 

1. Ensure that all other message process- 
ing programs, and all their QTAM data 
sets, are closed. 

2. Issue the CLOSEMC macro instruction 
(only one CLOSEMC is required to deac- 
tivate the entire system) . 

3. Close the MS destination and MS pro- 
cess queues data sets and any other 
data sets opened in that message pro- 
cessing program. If the processing 
program does not require a main 
storage queue data set, a dummy one 
must be supplied and opened. When 
this data set is closed, the message 
processing program requests the mes- 
sage control program to close down. 

4,. Issue a RETURN macro instruction in 
order to end the message processing 
job. 

When the QTAM termination routine that 
is called by the CLOSEMC macro is entered, 
the following action occurs. Outgoing mes- 
sage traffic continues on any lines that 
are not currently receiving messages. 
Meanwhile, incoming message traffic on each 
line is limited to the message currently 



being received over that line. When the 
last block of the current message is 
received,, no more incoming messages are 
accepted (i.e., the line is not repolled or 
reenabled) . As each such line becomes 
free* any outgoing messages that have been 
queued for that line are sent. In this 
manner, incoming message traffic declines 
to nothing, while outgoing message traffic 
continues until all messages have been 
sent. 

The QTAM termination routine monitors 
the closing of the QTAM data sets opened in 
the message processing programs. When it 
finds that all of these data sets have been 
closed, and all outgoing message traffic 
has ended, the routine issues a STOPLN 
macro instruction for each line in the sys- 
tem. When all lines have been stopped, 
control returns to the first instruction 
following the ENDREADY macro instruction in 
the message control program. This instruc- 
tion must begin a user-written routine (or 
branch to a routine) that deactivates the 
message control program. This deactivation 
routine must issue CLOSE macro instructions 
for each of the data sets opened in the 
message control program (i.e., the line 
group, checkpoint* and direct access mes- 
sage queues data sets). 

The last QTAM data set to be closed must 
be the direct access message queues data 
set. This is important,, because closing 
this data set constitutes deactivation of 
the telecommunications system. After the 
message queues data set has been closed* no 
further references can be made to queues., 
control blocks,, terminal table, polling 
lists,, etc. 

The deactivation routine should end with 
a RETURN macro instruction in order to end 
the message control jcb« Each of the mes- 
sage processing programs should also end 
with a RETURN. 



CLOSEMC Macro Instruction 



r t t 1 

j] Name | Operation] Operand | 

J [symbol] | CLOSEMC | | 

L J. JL J 

symbol 

Is the name of the macro instruction. 
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Note: The user is cautioned against using mode,, the close procedure will never com- 

the CLOSEMC macro instruction in the mes- plete„ and the QTAM message control program 

sage control program. A communications will remain in a wait state. A line may 

line on a transmission control unit may not not be in conversational mode (see the MODE 

be in CE mode when the CLOSEMC macro in- macro instruction in the MCP) when the 

struction is issued. If the TCU is in CE CLOSEMC macro instruction is issued. 
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APPENDIX A; QTAM CHECKPOINT DATA RECORD 



Record Format : 



r T T T T T T 1 

|t Next |t lSt|TERM ENTRIESJQCB ENTRIES | POLL LISTSJLCB ENTRIESJDEAD LETTER] 
| Disk Locj QCB | III 1QCB ENTRY* ] 

L 4 JL — 4 — J 



I Formats of Fields: 

1. Save all terminal entries (except distribution lists) 

r 



t 



TERM ENTRY 



(Terminal Table Entry ] 
j. ^ 

l size of TERM entry + 1 J 



2. Save QCBs only if current QCB is not the same as the last QCB saved. 

] PROCESS 
jQCB ONLY 

r T T T + 1 

QCB ENTRY |QSIZE| QNASE j QBACB |QFAC | t CURRENT] 

|| II |MSG HDR I 

3. Save polling list only if the list is not the same as the last polling list saved. 

r t t 1 

POLLING LIST | SIZE | STATUS JVARIAELE INFO] 

l — i_i 1 — x variable — J 

4. Save LCB information based on QRLM of current QCB being checkpointed. 

r T T T T T 

| LCBHDR | LCBTTIND | LCBSTATE | LCBNASEG | UNIT ADDR | 

L 3 — x 2 — J- 1 -»- 3 — J- 2 J 



I Control Record: 



r t 1 

| STATUS | Not Used | 
L J. J 



Status 

00 Normal Close 

01 Abnormal Termination: 
2 Abnormal Termination: 



(checkpoint reccrd 1 is good) 
(checkpoint record 2 is good) 



L J 
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APPENDIX B: FORMAT AND SUMMARY OF MACRO INSTRUCTIONS 



A format illustration accompanies each macro instruction description 
in this publication. The illustrations indicate which operands must be 
coded exactly as shown, which are required, which are variable,, etc. 
The conventions stated to describe the operands are as follows: 

1. Keyword operands are described either as the single word that must 
be coded as shown or by a three-part structure that consists of 
tne keyword operand, followed by an equal sign (both of which must 
be coded) , followed by a value mnemonic or a coded value. 

Examples : 



a. 
b. 



ALL 
TYPE=PQ 



2. 



3. 



4. 



5. 



7. 



Positional operands are described by a lowercase name that is 
merely a convenient reference to the operand and is never coded by 
the programmer. The programmer replaces the positional operand by 
an allowable expression. Expressions allowed are indicated at the 
left of the foldout page. The chart shows what expressions are 
allowable for each operand. 

Uppercase letters and punctuation marks (except as described in 
these conventions) represent information that must be coded 
exactly as shown. 

Lowercase letters and terms represent information that must be 
supplied by the programmer. More specifically, n indicates a 
decimal number, nn a decimal number with at most two digits,, nnn 
with at most three digits, etc. 

An ellipsis (a comma followed by three periods) indicates that a 
variable number of iterrs may be included. 



{} 
[] 



Options contained within braces represent alternatives,, 
one of which must be chosen. 

Information contained within brackets represents an 
option that can be included or omitted, depending on the 
requirements of the program. If more than one option is 
contained within brackets, any one or none of the options 
may be chosen. 

Underlined elements represent an assumed value in 
the event a parameter is omitted. 
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Abbreviations used in Chart 



Abbreviations 

SYM 

DEC DIG 

REGISTER 



RX type 



REL EXP 



ABS EXP 



CHAR 



HEX CHAR 



W/S 



Meaning 

Any symbol valid in the Assembler Language. 

Any decimal digits, up to the value indicated in the 
associated macro instruction description. 

A general register, always coded within parentheses, 
as follows: 

(2-12) one of general registers 2 thrcugh 12, previously 
loaded with the right-adjusted value or address 
indicated in the macro instruction description. The 
unused high-order bits must be set to zero. The 
register may be designated symbolically or with an 
absolute expression. 

(1) general register 1, previously loaded as indicated 
above. The register can be designated only as (1). 

(0) general register 0, previously loaded as indicated 
above. The register can be designated only as (0). 

Any address that is valid in the RX form of instruc- 
tion (e.g., LA) may be designated. 

A relocatable expression (acceptable as an A-type or 
V-type address constant by the assembler). 

Any absolute expression as defined by the assembler: 
self-defining terms (decimal* hexadecimal.^ binary^ 
character), length attributes,, absolute symbols, 
paired relocatable terms in the same CSECT, and 
arithmetic combinations of absolute terms, 

A character string (the frairing characters, C V, 
are not coded unless specifically indicated in the 
individual macro instruction description). 

Concatenated hexadecimal digits (the framing charac- 
ters* X' ', are not coded unless specifically indi- 
cated in the macro instruction description) . 

Written as shown. 



MACRO 
INSTRUCTION 


OPERANDS 


WRITTEN AS 


Sym 


Dec 
Dig 


REGISTER 


RX 
Type 


Rel 
Exp 


Abs 
Exp 


Char 


Hex 
Char 


W/S 


(2- 
12) 


0) 


CHNGP 


term name 






X 










X 






rln 




X 


X 
















/ workarea J 






X 




X 












\ =C'0' } 




















X 


(<■'' ) 




















X 


CHNGT 


termname 






X 










X 






workarea 






X 




X 












CLOSE 


deb 






X 






X 










MF= 




















X 


COPYP 


termname 






X 










X 






rln 




X 


X 
















workarea 






X 




X 












COPYQ 


termname 






X 










X 






workarea 






X 




X 












COPYT 


termname 






X 










X 






workarea 






X 




X 












GET 


deb 






X 






X 










( workarea ) 






X 




X 












1(0) ) 




















X 


OPEN 


deb 






X 






X 










INPUT 




















X 


OUTPUT 




















X 


MF= 




















X 


PUT 


deb 






X 






X 










workarea 






X 




X 












(0) 




















X 


RELEASEM 


termname 






X 










X 






RETRIEVE 


termname 






X 










X 






(dasdaddr) 






X 






X 










workarea 






X 




X 












fIN J 




















X 


I OUT) 




















X 


number 




X 
















X 


f s ) 




















X 


type= ( D j 




















X 


STARTLN 


termname 






X 










X 






(rln ) 




X 


X 
















(ALL) 




















X 


STOPLN 


termname 






X 










X 






f rln } 




X 


X 
















(ML) 




















X 
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APPENDIX C: RETURN CODES FOR MACRO INSTRUCTIONS USED TO MODIFY AND EXAMINE SYSTEM STATUS 



Upon return to the message processing rou- order byte«, right-adjusted,, in register 15. 
tine that issued the macro instruction* the All numbers in Figure 8 appear in hexadeci- 
following return codes are set in the low- mal notation. 



•T 

| Normal 
| Return 



T T 

Line not | Invalid | Invalid 
Inter- ] Relative ] Count 
cepted ] Line Number | 
I I 

ix'os* JX'IO* 

I |X'10« 

|X'08' ] 

I I 

1 ] 

X*04' ] | 



T 1 

Invalid Ter- ] Inval id 
minal Table j Sequence 
Entry or DCB| Number 
Name j 

X'20' ] 

X'20' ] 

X'20 - ] 

X^O* ] 

X^O 8 ) 

X'20* J 



Macro 



CHNGP |X'00' 

CHNGT IX'OO* 

COPYP ]X*00' 

COPYQ |X f 00 

COPYT IX'OO' 

RELEASEM IX^O 1 

RETRIEVE IX'OO" 
By disk | 
address j 

RETRIEVE IX'OO' 
By termi- | 
nal table j 
entry j 

STARTLN |X*00' 

STOPLN |X f 00* 
X 



Unopened 
DCB 



X'01' 
+ 4 4 

4 4 4 

X'Ol' 

4 4 4 



4 



X'Ol* 

x-oi' 



Invalid 

Disk 

Address 



4 

X'02' 






4 

4 



] 

IX'08" 

ix'os' 1 



X^O" |X'40' 



I IX'20" J 

X f 20« ] 

± 



Figure 8. Return Codes for Macro Instructions Used to Modify and 
Examine System Status 
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APPENDIX D: QTAM SAMPLE PROGRAM 



* * 

* PROGRAM: OS QTAM CLOSE ROUTINE MPP * 

* * 

* OBJECTIVE: SYSTEM CLOSEDOWN * 

* * 

* PROCEDURE: THE GET MACRO INSTRUCTION CAUSES QTAM TO PASS MESSAGE * 

* DATA (DESTINED FOR THE CLOSE ROUTINE) FROM THE MS PROCESS* 

* QUEUE TO THE USER-SPECIFIED WORK AREA (WORKAREA). IF NO * 

* MESSAGE DATA IS AVAILABLE FOR THE CLOSE RUUTINE, THE GET * 
MACRO INSTRUCTION IS UNSUCCESSFUL AND CONTROL RETURNS TO * 
THE SUPERVISOR * 



IF THE GET MACRO INSTRUCTION IS SUCCESSFUL THE CLOSEMC * 

MACRO INSTRUCTION IS EXECUTED. CLOSEMC STOPS ALL * 

INCOMING MESSAGE TRAFFIC AS SOON AS ALL CURRENTLY * 

INCOMING MESSAGES ARE RECEIVED. THEN CLOSEMC CAUSES ALL * 

OUTGOING MESSAGES TO BE SENT. * 

THE CLOSE MACRO INSTRUCTION CLOSES ALL DATA SETS OPENED * 
IN THE CLOSE ROUTINE. * 

THE RETURN MACRO INSTRUCTION RETURNS CONTROL TO THE FIRST* 
INSTRUCTION AFTER ENDREADY IN THE MCP. * 

* 



CLOSRTN CSECT 





SAVE 


(14,12) 




BALR 


12,0 




USING 


*,12 




ST 


13,SAVEAREA+4 




LA 


13, SAVEAREA 




B 


OPENN 


WORKAREA 


DC 


CL20» ' 


SAVEAREA 


DC 


18F'0« 


SOURCE 


DC 


CL3« ' 


INDCB 


DCB 


DSORG=MQ, * 
MACRF=G, * 
DDNAME=EOJ, * 
S0WA=20, * 
RECFM=R, * 
TRMAD=SOURCE 


OPENN 


OPEN 


( INDCB, ( INPUT) ) 




GET 


INDCB, WORKAREA 


FINISH 


CLOSEMC 




CLOSE 


( INDCB) 




RETURN 




END 


CLOSRTN 



Remarks 



Location provided for the name of the sending terminal. 

Data set organization is a TP message process queue. 

A GET is used to gain access to the message process queue. 

Name of DD card and process macro instruction in term table. 

Size of the user-provided work area. 

Name of the work unit is a record. 

Location provided for the name of the sending terminal. 

Opens the MPP data set. 

GET is performed when a message is sent to EOT. 

Stops the message traffic in the MCP. 

Closes the MPP data set. 

Return to the MCP. 
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Where more than one page reference appears, 
the major reference appears first. 

Access method 5 
Analysis routine 6,13 

Buffers 8,5,17 

Checkpoint data record format 35 
Checkpointing the message control program 

32 
CHNGP macro instruction 27-28 
CHNGT macro instruction 25-26 
CHREQ macro instruction 32 
CLOSE macro instruction 18 
CLOSEMC macro instruction 33-34 
Closing the message control program 33-34 
Code 

destination 6,8 
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